Artigo

Photo by Arpit Rastogi on Unsplash

If you’ve written anything in C#, you’ll have come across Using Directives.

By using them (no pun intended) you can reference types within that namespace, without having to fully qualify the type name.

A quick re-cap of Using Directives

Most C# files will reference types that exist in another namespace. Without any Using Directives, these types have to be fully qualified, so that the namespace is included in the name of the type:

C# code showing a type being fully qualified since it’s coming from a different namespace

Here you can see the property has been defined with the type StringBuilder, and since this type is in the System.Text namespace, the type has been fully qualified and included when StringBuilder is referenced.

Usually this is refactored to use a Using Directive for that namespace, so that the namespace doesn’t need to be repeated throughout the file:

C# code showing a Using Directive so that a type in that namespace can be referenced directly

Introducing Global Using Directives

As part of .NET 6/C# 10, a new feature called Global Using Directives has been introduced.

This feature allows you to add a Using Directive that applies across your entire project.

Let’s see how this works.

To create a Global Using Directive, all you do is add the global keyword before a Using Directive:

C# code showing how to define a Global Using Statement

This needs to be included somewhere in your project. The common convention is that you add a Usings.cs file in the root of your project, to contain all of the directives like this.

Once you’ve set this up, this Using Directive is applied to all files in the project. This means we can remove that Using Directive from all other files in the project, and still reference types within that namespace:

C# code showing a type being referenced from a different namespace without any Using Directives in the file itself

Benefits of Global Using Directives

Global Using Directives are perfect for when you’ve got a Using Directive that you’re going to be using in multiple files, and you want to save some space in your individual files.

As your codebase matures, it’s possible for the number of Using Directives to grow within each file, and I’ve seen some extreme cases where there are over 50 directives all listed there, meaning you have to scroll a fair bit before you even get to the actual code in that file.

Global Using Directives can really help in situations like this by enabling you to move common directives out of your individual files.

Additionally, you can use the global modifier on namespace aliases, as well as being combined with the static modifier.

We’ll go through each of those now.

Combining Global Using Directives with aliases

Namespace aliases allow you to define an alias for a particular alias. This can be to give a short name for a namespace that you find to be too long to deal with, or for when you’ve got the same type name defined in multiple namespaces and you want to reference both at the same time.

To make a namespace alias global, just add the global keyword to the alias itself:

C# code showing how a namespace alias can be made global

You can then reference this alias in any file in your project, without having to redefine it:

C# code showing how a namespace alias can be referenced even though it’s not defined in the same file

Combining Global Using Directives with static

Static Using Directives allow you to expose the static methods within a type, so that you can use them directly in your code. These can also be made global, by adding the global keyword.

For example, to expose all static methods within System.Math across your entire project, add the global keyword to the static Using Directive:

C# code showing how a static Using Directive can be made global

You can then use any method within System.Math (such as Min) anywhere in your project:

C# code showing how static methods can be directly referenced without the type or static Using Directive included in the same file

Implicit Global Using Directives

It is also possible to enable implicit Global Using Directives for your project. This automatically adds a number of common Global Using Directives based upon the type of project you’re using.

You can enable implicit Using Directives by adding the <ImplicitUsings> property to your .csproj file:

Project file showing how to enable implicit Using Directives

For C# Class Library projects, this automatically adds the following Global Using Directives to your project:

C# code showing the implicit Using Directives added for a Class Library

This is great, because it means you don’t need to worry about defining these directives manually — either within your files, or as global directives. They’re just there ready for you to use.

As another example, ASP.NET Core Web App projects adds these directives automatically:

C# code showing the implicit Using Directives added for an ASP.NET Core Web App

So we can see there’s a whole bunch of extra directives added there, specifically for ASP.NET Core.

If you want to check out what implicit Using Directives you’ve currently got in your project, open the Obj folder within your project and look for a file called [ProjectName].GlobalUsings.g.cs — this is the file that contains all these implicit directives.

If you’d rather control these directives yourself, instead of them being defined automatically, you can easily disable these implicit Using Directives within your .csproj file:

Project file showing how to disable implicit Using Directives

Note that for new .NET 6 projects, this property is enabled by default, so it’s useful to know what it’s doing.

Summary

By using Global Using Directives, you can avoid duplicating Using Directives across all your files. This can make your individual files cleaner, and let you get to your code quicker, without having to scroll down as far.

They can also let you centralise any alias or static directives, so you don’t need to explicitly define them for when you want to use them.

Implicit Global Using Directives further reduce the amount of work you need to do, by automatically including the common namespaces that you’re likely to need for your current type of project.